<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Llama Factory 在 macOS (M2 芯片) 上的部署指南</title>
    <script src="https://cdn.tailwindcss.com"></script>
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0-beta3/css/all.min.css">
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
    <style>
        /* 自定义样式 (与原指南类似) */
        body {
            font-family: 'Inter', sans-serif;
            background-color: #f3f4f6;
        }
        pre {
            background-color: #1f2937; color: #d1d5db; padding: 1rem;
            border-radius: 0.5rem; overflow-x: auto; position: relative;
            margin-bottom: 1rem;
        }
        /* 内联代码和kbd标签样式 */
        code, kbd {
            font-family: 'Courier New', Courier, monospace;
            background-color: #e5e7eb; /* 浅灰色背景 */
            color: #374151; /* 深灰色文字 */
            padding: 0.1rem 0.3rem;
            border-radius: 0.25rem; /* 轻微圆角 */
            font-size: 0.9em; /* 比普通文本稍小 */
        }
        pre code { /* pre 块内的 code 不应用背景色 */
          background-color: transparent;
          color: inherit;
          padding: 0;
          border-radius: 0;
          font-size: inherit;
        }
        kbd { /* 按键样式 */
           border: 1px solid #d1d5db;
           box-shadow: 1px 1px 1px rgba(0,0,0,0.1);
        }
        .copy-button {
            position: absolute; top: 0.5rem; right: 0.5rem;
            background-color: #4b5563; color: white; border: none;
            padding: 0.3rem 0.6rem; border-radius: 0.375rem; cursor: pointer;
            font-size: 0.8rem; transition: background-color 0.2s;
        }
        .copy-button:hover { background-color: #6b7280; }
        h2 {
            border-bottom: 2px solid #6366f1; padding-bottom: 0.5rem;
            margin-top: 2rem; margin-bottom: 1rem; font-size: 1.5rem;
            font-weight: 600; color: #1f2937;
        }
        h3 {
            margin-top: 1.5rem; margin-bottom: 0.75rem; font-size: 1.25rem;
            font-weight: 600; color: #374151;
        }
        /* 添加 h4 样式 */
        h4 {
            margin-top: 1.25rem;
            margin-bottom: 0.5rem;
            font-size: 1.1rem;
            font-weight: 600;
            color: #4b5563; /* 比 h3 稍浅的灰色 */
        }
        .info-box {
            background-color: #e0e7ff; border-left: 4px solid #6366f1;
            padding: 1rem; margin: 1rem 0; border-radius: 0.375rem;
            color: #3730a3;
        }
        .warning-box {
            background-color: #fffbeb; border-left: 4px solid #f59e0b;
            padding: 1rem; margin: 1rem 0; border-radius: 0.375rem;
            color: #b45309;
        }
         .danger-box {
            background-color: #fef2f2; /* 浅红色背景 */
            border-left: 4px solid #ef4444; /* 红色左边框 */
            padding: 1rem;
            margin: 1rem 0;
            border-radius: 0.375rem; /* 圆角 */
            color: #b91c1c; /* 深红色文字 */
        }
        .success-box {
            background-color: #f0fdf4; border-left: 4px solid #22c55e;
            padding: 1rem; margin: 1rem 0; border-radius: 0.375rem;
            color: #15803d;
        }
        details > summary {
            cursor: pointer; font-weight: 500; color: #4f46e5;
            margin-bottom: 0.5rem;
        }
        .interactive-container {
            border: 1px dashed #9ca3af; padding: 1rem; margin-top: 1rem;
            border-radius: 0.5rem; background-color: #ffffff;
        }
        .terminal-output {
            background-color: #111827; color: #9ca3af; padding: 0.75rem;
            border-radius: 0.375rem; font-family: 'Courier New', Courier, monospace;
            font-size: 0.9rem; white-space: pre-wrap; word-wrap: break-word;
        }
        .action-button {
            background-color: #6366f1; color: white; padding: 0.5rem 1rem;
            border-radius: 0.375rem; cursor: pointer; transition: background-color 0.2s;
            font-weight: 500; margin-right: 0.5rem;
        }
        .action-button:hover { background-color: #4f46e5; }
        .image-container {
            margin: 1rem 0; text-align: center; background-color: #e5e7eb;
            padding: 1rem; border-radius: 0.5rem;
        }
        .image-container img {
            max-width: 100%; height: auto; border-radius: 0.375rem;
            box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
        }
        .image-caption {
            font-size: 0.875rem; color: #6b7280; margin-top: 0.5rem;
        }
        /* 列表样式 */
        ol { list-style-type: decimal; margin-left: 1.5rem; }
        ul { list-style-type: disc; margin-left: 1.5rem; }
        li { margin-bottom: 0.5rem; }
    </style>
</head>
<body class="p-4 md:p-8">

    <div class="max-w-4xl mx-auto bg-white shadow-lg rounded-lg p-6 md:p-10">

        <h1 class="text-3xl font-bold text-center text-gray-800 mb-6">
            <i class="fab fa-apple mr-2 text-indigo-600"></i>Llama Factory 在 macOS (M2 芯片) 上的部署指南
        </h1>

        <p class="text-gray-600 mb-6">
            欢迎！本指南旨在帮助您在配备 M2 芯片的 macOS 设备上安装和配置 Llama Factory。请注意，macOS 并非 Llama Factory 的主要目标平台，尤其在模型微调方面性能会远低于配备 NVIDIA GPU 的 Linux 系统。本指南主要目的在于帮助您熟悉 Llama Factory 的安装流程、配置界面和进行基础的模型推理（对话）体验。
        </p>

        <div class="danger-box">
            <p><i class="fas fa-tachometer-alt mr-1"></i><strong>性能预期警告：</strong></p>
            <ul class="list-disc list-inside ml-4 mt-1 text-sm">
                <li><strong>模型微调 (Fine-tuning):</strong> 在 M2 Mac 上进行微调会**非常缓慢**，可能需要极长的时间，对于学习目的而言效率不高，不推荐作为主要的微调平台。</li>
                <li><strong>模型推理 (Inference):</strong> 使用 Metal (MPS) 或 CPU 进行推理是可行的，特别是对于较小模型，但速度仍会慢于 NVIDIA GPU。</li>
                <li><strong>兼容性：</strong> 某些依赖或功能可能在 macOS 上存在兼容性问题。</li>
            </ul>
            <p class="mt-2 text-sm">建议将 Mac 上的部署视为熟悉工具和流程的方式，实际的微调任务建议使用云 GPU 平台（如 Colab, Kaggle, AutoDL 等）。</p>
        </div>

        <section id="intro">
            <h2><i class="fas fa-info-circle mr-2"></i>1. Llama Factory 简介</h2>
             <p class="text-gray-700 mb-4">
                Llama Factory 是一个强大的开源框架，专门用于微调（Fine-tuning）各种开源大型语言模型（LLM）。它提供了简洁易用的接口和丰富的功能，使得研究人员和开发者能够更方便地在自己的数据集上训练和优化模型。
            </p>
            <div class="info-box">
                <p><i class="fas fa-lightbulb mr-1"></i><strong>核心功能：</strong> 支持多种主流开源模型、多种微调方法（LoRA, QLoRA, Full-tuning等）、易于扩展、提供 Web UI 界面方便操作。</p>
            </div>
        </section>

        <section id="prerequisites-macos">
            <h2><i class="fas fa-check-circle mr-2"></i>2. 依赖环境与准备 (macOS)</h2>
            <p class="text-gray-700 mb-4">
                在开始安装 Llama Factory 之前，请确保您的 M2 Mac 满足以下要求：
            </p>
            <ul class="list-disc list-inside space-y-2 text-gray-700 mb-4">
                <li><strong>操作系统：</strong> macOS (建议使用较新版本，如 Ventura 或 Sonoma)</li>
                <li><strong>芯片：</strong> Apple Silicon (M1, M2, M3 系列)</li>
                <li><strong>Python 版本：</strong> <code>3.10</code> 或 <code>3.11</code> (推荐 <code>3.11</code>)</li>
                <li><strong>PyTorch：</strong> 需要安装支持 Apple Silicon (Metal/MPS) 的版本。</li>
                <li><strong>包管理工具：</strong> Conda (推荐使用 Anaconda 或 Miniconda) 或 Homebrew + venv/pip。本指南以 Conda 为例。</li>
                <li><strong>Xcode Command Line Tools：</strong> 某些依赖可能需要编译，需要安装 Xcode 命令行工具。</li>
                 <li><strong>(可选) DeepSpeed：</strong> <span class="text-red-600 font-semibold">不推荐</span>在 macOS 上安装，它主要依赖 CUDA，兼容性很差。</li>
            </ul>
             <p class="text-gray-700 mb-2">检查并安装 Xcode Command Line Tools (如果尚未安装)：</p>
             <pre><code>xcode-select --install</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>
             <p class="text-sm text-gray-500 mb-4">如果已安装，会提示 "command line tools are already installed"。否则会弹出安装窗口。</p>
            <details class="mb-4">
                <summary><i class="fas fa-question-circle mr-1"></i>版本匹配的重要性</summary>
                <div class="p-3 bg-gray-50 rounded border mt-2 text-sm text-gray-600">
                    虽然 macOS 环境与 Linux 不同，但 Python 版本、PyTorch 版本及其与其他库（如 transformers, datasets）的兼容性依然重要。使用推荐的 Python 版本 (3.11) 和最新稳定版的 PyTorch for Mac 有助于减少依赖冲突和运行时错误。
                </div>
            </details>
        </section>

        <section id="environment-setup-macos">
            <h2><i class="fas fa-tools mr-2"></i>3. 环境配置 (macOS)</h2>
            <p class="text-gray-700 mb-4">
                我们将使用 Conda 来创建和管理 Llama Factory 的运行环境。
            </p>
            <h3>3.1 安装 Conda (如果需要)</h3>
            <p class="text-gray-700 mb-4">
                如果您尚未安装 Conda，请访问 <a href="https://docs.conda.io/projects/miniconda/en/latest/" target="_blank" class="text-indigo-600 hover:underline">Miniconda 官网</a> 或 <a href="https://www.anaconda.com/download" target="_blank" class="text-indigo-600 hover:underline">Anaconda 官网</a> 下载适用于 macOS (Apple Silicon, pkg 或 sh 安装包) 的安装程序并进行安装。
            </p>
            <p class="text-gray-700 mb-2">安装完成后，打开**新的**终端窗口或重新加载配置文件 (如 <code>source ~/.zshrc</code>)，验证 Conda 是否安装成功：</p>
            <pre><code>conda --version</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>
             <div class="interactive-container">
                <p class="mb-2 font-medium text-gray-800">预期输出 (版本号可能不同):</p>
                <div class="terminal-output" id="conda-version-output-macos">
                    conda 23.7.4
                </div>
            </div>
            <h3>3.2 创建并激活 Conda 虚拟环境</h3>
            <p class="text-gray-700 mb-2">
                为 Llama Factory 创建一个独立的 Conda 环境，使用 Python 3.11。
            </p>
            <pre><code>conda create -n llama_factory python=3.11 -y</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>
            <p class="text-gray-700 my-2">创建完成后，激活该环境：</p>
            <pre><code>conda activate llama_factory</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>
            <div class="interactive-container">
                <p class="mb-2 font-medium text-gray-800">交互演示：</p>
                <button class="action-button" onclick="simulateActivateEnvMac()">模拟激活环境</button>
                <div class="terminal-output mt-2" id="conda-env-output-macos">
                    (base) user@MacBook-Pro ~ % conda activate llama_factory
                    <span id="prompt-indicator-macos" class="hidden text-green-400">(llama_factory)</span> user@MacBook-Pro ~ %
                </div>
                 <p class="mt-3 text-sm text-gray-600">
                    <i class="fas fa-check mr-1"></i>激活成功后，您终端提示符前面会显示 <code>(llama_factory)</code>。
                </p>
            </div>
            <h3>3.3 安装 PyTorch for Apple Silicon</h3>
            <p class="text-gray-700 mb-2">
                在已激活的 <code>llama_factory</code> 环境中，安装适用于 Apple Silicon 的 PyTorch。通常直接使用 pip 即可安装最新稳定版，它会自动包含 Metal (MPS) 后端支持。
            </p>
             <p class="text-gray-700 mb-2">
                访问 <a href="https://pytorch.org/get-started/locally/" target="_blank" class="text-indigo-600 hover:underline">PyTorch 官网</a> 确认最新的 macOS 安装命令（通常是默认的 pip 命令）。
            </p>
            <pre><code>pip3 install torch torchvision torchaudio</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>
             <div class="info-box">
                 <p><i class="fas fa-info-circle mr-1"></i> 如果遇到网络问题，可以尝试添加国内镜像源：<code>pip3 install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple</code></p>
             </div>
            <p class="text-gray-700 mt-4 mb-2">安装完成后，验证 PyTorch 是否能正确识别 Metal (MPS) 后端：</p>
            <pre><code>python -c "import torch; print(f'PyTorch version: {torch.__version__}'); print(f'MPS available: {torch.backends.mps.is_available()}'); print(f'MPS built: {torch.backends.mps.is_built()}')"</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>
            <div class="interactive-container">
                 <p class="mb-2 font-medium text-gray-800">预期输出 (版本号会根据您的安装而变化):</p>
                <div class="terminal-output" id="pytorch-check-output-macos">
                    PyTorch version: 2.1.0 <br>
                    MPS available: <span class="text-green-400 font-bold">True</span>
                    <br>
                    MPS built: <span class="text-green-400 font-bold">True</span>
                </div>
                 <p class="mt-3 text-sm text-gray-600">
                    <i class="fas fa-check-circle text-green-500 mr-1"></i>如果 <code>MPS available</code> 和 <code>MPS built</code> 都显示 <code>True</code>，则表示 PyTorch 已成功安装并能尝试使用您的 M2 芯片进行加速。
                </p>
                 <p class="mt-1 text-xs text-gray-500">
                    注意：即使 MPS 可用，实际的加速效果和稳定性也取决于具体模型和操作，可能不如 CUDA 成熟。
                </p>
            </div>
        </section>

        <section id="download-llama-factory-macos">
            <h2><i class="fas fa-download mr-2"></i>4. 下载 Llama Factory</h2>
             <p class="text-gray-700 mb-4">
                与 Linux 环境类似，您可以选择使用 Git 克隆或下载 ZIP 压缩包。推荐使用 Git。
            </p>
            <p class="text-gray-700 mb-4">
                Llama Factory 的 GitHub 仓库地址：<a href="https://github.com/hiyouga/LLaMA-Factory" target="_blank" class="text-indigo-600 hover:underline">https://github.com/hiyouga/LLaMA-Factory</a>
            </p>

            <h3>4.1 方法一：使用 Git 克隆 (推荐)</h3>
             <p class="text-gray-700 mb-2">macOS 通常自带 Git。打开终端，进入您想存放项目的目录（例如 <code>~/Projects</code>）：</p>
            <pre><code>cd ~/Projects # 进入您选择的目录
git clone https://github.com/hiyouga/LLaMA-Factory.git</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>
            <div class="info-box">
                <p><i class="fas fa-folder-open mr-1"></i>克隆完成后，会在当前目录下创建一个名为 <code>LLaMA-Factory</code> 的文件夹。<strong>请记住这个路径</strong>。</p>
            </div>

            <h3>4.2 方法二：下载 ZIP 压缩包</h3>
            <p class="text-gray-700 mb-2">
                访问 Llama Factory 的 GitHub 页面，点击 "Code" -> "Download ZIP"。下载后，在 Finder 中找到 <code>LLaMA-Factory-main.zip</code> 并解压（通常双击即可）。
            </p>
            <p class="text-gray-700 my-2">
                解压后会得到 <code>LLaMA-Factory-main</code> 文件夹（通常在您的“下载”文件夹里）。建议将其移动到您的项目目录下（例如 <code>~/Projects/</code>），并重命名为 <code>LLaMA-Factory</code> 以保持一致性。
            </p>

            <h4 class="text-gray-700"><i class="fas fa-search-location mr-1"></i>如何找到解压后的文件夹路径？</h4>
            <p class="text-gray-600 mb-2 text-sm">
                如果您不确定解压后的 <code>LLaMA-Factory-main</code> 文件夹在哪里，或者想确认它的完整路径，可以使用 Finder 的“路径栏”功能：
            </p>
            <ol class="list-decimal list-inside space-y-1 text-sm text-gray-600 mb-3">
                <li>打开一个新的 Finder 窗口。</li>
                <li>在屏幕顶部的菜单栏中，点击 **“显示” (View)**。</li>
                <li>选择 **“显示路径栏” (Show Path Bar)**。</li>
                <li>导航到您认为文件夹所在的目录（很可能是“下载”文件夹）。</li>
                <li>点击选中 <code>LLaMA-Factory-main</code> 文件夹。</li>
                <li>此时，Finder 窗口底部就会显示出该文件夹的完整路径。</li>
            </ol>
            <p class="text-gray-600 mb-2 text-sm">
                或者，您可以右键点击文件夹，选择 **“显示简介” (Get Info)**，在“位置” (Where) 字段查看其父目录路径。
            </p>
            <p class="text-gray-600 mb-4 text-sm">
                <i class="fas fa-lightbulb mr-1 text-indigo-500"></i>**提示:** 找到路径后，强烈建议将此文件夹移动到您的常用项目目录（如 <code>~/Projects/</code>）并重命名为 <code>LLaMA-Factory</code>，方便后续在终端中使用 <code>cd ~/Projects/LLaMA-Factory</code> 命令进入。
            </p>
            <div class="info-box">
                 <p><i class="fas-regular fa-folder-closed mr-1"></i>移动并重命名后，您就有了一个位于项目目录下的 <code>LLaMA-Factory</code> 文件夹。<strong>请记住这个最终路径</strong>。</p>
            </div>
        </section>

        <section id="install-dependencies-macos">
            <h2><i class="fas fa-box-open mr-2"></i>5. 安装 Llama Factory 依赖</h2>
            <p class="text-gray-700 mb-4">
                首先，建议升级 pip、setuptools 和 wheel，以获取最新的包管理功能。
            </p>
            <pre><code>pip install --upgrade pip setuptools wheel</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>

            <p class="text-gray-700 my-2">
                然后，**确保您已经进入了 Llama Factory 的项目目录** (例如 <code>cd ~/Projects/LLaMA-Factory</code>)，然后运行以下命令来安装其核心依赖：
            </p>
            <pre><code>pip install -r requirements.txt</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>

            <div class="warning-box my-4">
                 <p><i class="fas fa-exclamation-triangle mr-1"></i><strong>注意：</strong> 在 macOS 上安装依赖可能会遇到问题。如果安装过程中断或报错，请参考下面的小节。</p>
            </div>

            <h4><i class="fas fa-wrench mr-1"></i>5.1 可能遇到的安装问题及建议</h4>
            <p class="text-gray-600 mb-3 text-sm">
                在 macOS 上使用 <code>pip install -r requirements.txt</code> 时，您可能会遇到以下常见问题：
            </p>
            <ul class="list-disc list-inside space-y-2 text-sm text-gray-600 mb-4">
                <li>
                    <strong>依赖安装失败 (Missing Wheels):</strong> 某些 Python 包（特别是那些需要 C++ 或 Rust 代码编译的）可能没有为您的 macOS 版本和架构（arm64 for M2）提供预编译好的二进制文件 (称为 "wheels")。这会导致 pip 尝试从源码编译，如果缺少必要的编译工具或系统库，就会失败。
                </li>
                <li>
                    <strong>编译错误 (Compilation Errors):</strong> 如果 pip 尝试从源码编译但失败，您会看到大量的编译错误日志。这通常指向：
                    <ul class="list-disc list-inside ml-6 mt-1">
                        <li>缺少 Xcode Command Line Tools：请确保已通过 <code>xcode-select --install</code> 安装。</li>
                        <li>缺少特定的编译工具 (如 cmake, rustc) 或库 (如 protobuf)：您可能需要使用 <a href="https://brew.sh/" target="_blank" class="text-indigo-600 hover:underline">Homebrew</a> (macOS 的包管理器) 来安装它们。例如： <code>brew install cmake protobuf rust</code> (具体需要安装什么取决于报错信息)。</li>
                    </ul>
                </li>
            </ul>
             <p class="text-gray-600 mb-3 text-sm">
                <strong>解决策略：</strong>
            </p>
             <ul class="list-disc list-inside space-y-2 text-sm text-gray-600 mb-4">
                 <li>
                    <strong>仔细阅读错误信息：</strong> 终端输出的**完整错误日志**是关键。向上滚动查找第一个出现的 "error:" 或 "failed building wheel for..." 的地方，这通常能指明是哪个包安装失败以及可能的原因。
                 </li>
                 <li>
                    <strong>搜索解决方案：</strong> 将关键的错误信息（例如 "error: command 'clang' failed with exit status 1" 或特定库的编译错误）复制到搜索引擎中，通常能找到其他 macOS 用户遇到的类似问题和解决方案（可能需要在 Stack Overflow 或 GitHub Issues 中查找）。
                 </li>
                  <li>
                    <strong>尝试单独安装失败的包：</strong> 有时候，单独使用 <code>pip install &lt;package_name&gt;</code> 安装失败的包，并解决其特定的编译问题后，再重新运行 <code>pip install -r requirements.txt</code> 可能会成功。
                 </li>
                 <li>
                    <strong>接受功能限制：</strong> 如果某个非核心依赖实在无法在 macOS 上安装，您可能需要接受 Llama Factory 的部分功能（例如与该依赖相关的特定优化或特性）无法使用。
                 </li>
             </ul>
            <p class="text-gray-700 mt-4 mb-2">
                <strong>(可选) 使用国内镜像源加速：</strong> 如果下载速度慢，可以在安装命令后添加 <code>-i https://pypi.tuna.tsinghua.edu.cn/simple</code> 参数。
            </p>
            <pre><code>pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>
        </section>

        <section id="verify-installation-macos">
            <h2><i class="fas fa-clipboard-check mr-2"></i>6. 验证安装</h2>
            <p class="text-gray-700 mb-4">
                进行检查，确保 Llama Factory 及其核心依赖（特别是 PyTorch 和 MPS）已配置。
            </p>
            <h3>6.1 再次检查 PyTorch 和 MPS</h3>
            <p class="text-gray-700 mb-2">
                再次确认 PyTorch 和 MPS 的状态。
            </p>
            <pre><code>python -c "
import torch
import warnings

warnings.filterwarnings('ignore', category=UserWarning)

try:
    print(f'--- PyTorch & MPS Check ---')
    print(f'PyTorch version: {torch.__version__}')
    mps_available = torch.backends.mps.is_available()
    mps_built = torch.backends.mps.is_built()
    print(f'MPS available: {mps_available}')
    print(f'MPS built: {mps_built}')
    if mps_available:
        print('MPS backend is available and can be potentially used for acceleration.')
        # 尝试分配一个张量到 MPS 设备
        try:
            tensor_mps = torch.tensor([1.0, 2.0], device='mps')
            print(f'Successfully created a tensor on MPS device: {tensor_mps}')
        except Exception as e_mps:
            print(f'Could not create tensor on MPS device: {e_mps}')
    else:
        print('MPS not available. Llama Factory will likely run on CPU.')
    print(f'---------------------------')
except Exception as e:
    print(f'An error occurred during check: {e}')
"</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>
            <div class="interactive-container">
                 <p class="mb-2 font-medium text-gray-800">预期成功输出 (示例):</p>
                <div class="terminal-output" id="final-pytorch-check-output-macos">
                    --- PyTorch & MPS Check ---<br>
                    PyTorch version: 2.1.0<br>
                    MPS available: <span class="text-green-400 font-bold">True</span><br>
                    MPS built: <span class="text-green-400 font-bold">True</span><br>
                    MPS backend is available and can be potentially used for acceleration.<br>
                    Successfully created a tensor on MPS device: tensor([1., 2.], device='mps:0')<br>
                    ---------------------------
                </div>
                 <p class="mt-3 text-sm text-gray-600">
                    <i class="fas fa-check-circle text-green-500 mr-1"></i>确保 MPS 可用，并能成功在 MPS 设备上创建张量。
                </p>
            </div>

            <h3>6.2 检查 Llama Factory 命令行工具</h3>
            <p class="text-gray-700 mb-2">
                验证 <code>llama-factory-cli</code> 工具是否可用。**请确保您当前位于 Llama Factory 的项目目录下** (例如 <code>~/Projects/LLaMA-Factory</code>)。
            </p>
            <pre><code>llama-factory-cli -h</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>
            <div class="interactive-container">
                <p class="mb-2 font-medium text-gray-800">预期输出 (与 Linux 类似，展示开头部分):</p>
                <div class="terminal-output" style="max-height: 250px; overflow-y: auto;">
                    usage: llama-factory-cli [-h] {train,eval,infer,webchat,webui,version,export} ...<br>
                    <br>
                    LLaMA Factory CLI<br>
                    ... (omitted for brevity) ...
                </div>
                 <p class="mt-3 text-sm text-gray-600">
                    <i class="fas fa-check-circle text-green-500 mr-1"></i>如果看到帮助信息，表示 CLI 工具基本可用。如果报错，请参考下面的解决步骤。
                </p>
            </div>

            <h4><i class="fas fa-wrench mr-1"></i>6.3 解决 "command not found: llama-factory-cli" 错误</h4>
            <p class="text-gray-600 mb-3 text-sm">
                如果您在运行 <code>llama-factory-cli -h</code> 时遇到 "command not found" (命令未找到) 的错误，通常有以下原因：
            </p>
            <ul class="list-disc list-inside space-y-2 text-sm text-gray-600 mb-4">
                <li>
                    <strong>依赖安装未完成或出错：</strong> 第 5 步的 <code>pip install -r requirements.txt</code> 可能没有成功安装所有包，特别是与 <code>llama-factory-cli</code> 相关的核心包。请检查第 5 步的输出是否有错误。
                </li>
                <li>
                    <strong>未在正确的 Conda 环境中：</strong> 确认您的终端提示符前有 <code>(llama_factory)</code> 标识。
                </li>
                 <li>
                    <strong>未在正确的项目目录中：</strong> <code>llama-factory-cli</code> 命令有时需要在 Llama Factory 项目的根目录下才能被正确找到或执行。请确保您已通过 <code>cd ~/Projects/LLaMA-Factory</code> (或您的实际路径) 进入了该目录。
                </li>
                 <li>
                    <strong>环境路径问题：</strong> 极少数情况下，Conda 环境的路径 (PATH) 可能没有正确配置，导致找不到新安装的命令。
                </li>
            </ul>
             <p class="text-gray-600 mb-3 text-sm">
                <strong>尝试以下步骤解决：</strong>
            </p>
             <ol class="list-decimal list-inside space-y-2 text-sm text-gray-600 mb-4">
                 <li>
                    <strong>确认环境和目录：</strong> 再次确认您处于 <code>(llama_factory)</code> 环境下，并且位于 <code>LLaMA-Factory</code> 项目目录中 (使用 <code>pwd</code> 命令检查当前路径)。
                 </li>
                 <li>
                    <strong>尝试本地安装：</strong> 在 <code>LLaMA-Factory</code> 目录下，运行 <code>pip install .</code> 命令。这会执行项目自带的安装脚本，有时能解决命令链接问题。
                    <pre><code>pip install .</code><button class="copy-button" onclick="copyCode(this.previousElementSibling)"><i class="far fa-copy"></i> 复制</button></pre>
                 </li>
                 <li>
                    <strong>重新激活环境：</strong> 退出并重新激活 Conda 环境可能有助于刷新路径设置。
                    <pre><code>conda deactivate
conda activate llama_factory</code><button class="copy-button" onclick="copyCode(this.previousElementSibling)"><i class="far fa-copy"></i> 复制</button></pre>
                 </li>
                  <li>
                    <strong>检查依赖安装日志：</strong> 如果上述步骤无效，请回看第 5 步 <code>pip install -r requirements.txt</code> 的输出，查找是否有关键包安装失败的错误信息。
                 </li>
             </ol>
             <div class="success-box mt-6">
                 <p><i class="fas fa-check-double mr-1"></i><strong>基本就绪！</strong> 如果验证步骤通过，您的 Llama Factory 环境已在 macOS 上初步设置完成。准备好进行下一步（模型下载与推理验证）吧！</p>
            </div>
        </section>

        <section id="finetune-example-macos">
            <h2><i class="fas fa-rocket mr-2"></i>7. 示例：准备与验证模型 (通义千问 Qwen1.5-1.8B)</h2>
            <p class="text-gray-700 mb-4">
                我们将下载 Qwen1.5-1.8B-Chat 模型，并尝试使用 Llama Factory 的 `webchat` 功能在 M2 Mac 上运行它进行推理验证。
            </p>

            <h3>7.1 下载模型 (使用 ModelScope 或 Hugging Face Hub)</h3>
            <p class="text-gray-700 mb-2">
                Llama Factory 通常推荐使用 ModelScope 下载国内模型。但 ModelScope 在 macOS M2 上可能存在兼容性问题。
            </p>
            <pre><code># 尝试安装 ModelScope (如果失败，请使用下面的 Hugging Face Hub 替代方案)
pip install modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>
            <p class="text-gray-700 my-2">如果 ModelScope 安装成功，尝试用它下载模型：</p>
            <pre><code># 使用 ModelScope 下载 (如果安装成功)
python -m modelscope.cli.download --model Tongyi-Qianwen/Qwen1.5-1.8B-Chat --revision master</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>
            <p class="text-sm text-gray-500 mb-4">
                模型默认下载到 <code>~/.cache/modelscope/hub/</code>。如果此步骤失败，请看下面的替代方案。
            </p>

            <h4><i class="fas fa-exclamation-circle mr-1"></i>7.1.1 解决 ModelScope 安装/下载问题 (及替代方案)</h4>
            <p class="text-gray-600 mb-3 text-sm">
                如果您在运行 <code>pip install modelscope</code> 时遇到 <code>ERROR: No matching distribution found for modelscope</code> 错误，这很可能是因为 ModelScope 没有提供与您的 macOS M2 (arm64) 或 Python 3.11 兼容的预编译版本。
            </p>
             <p class="text-gray-600 mb-3 text-sm">
                <strong>推荐替代方案：使用 Hugging Face Hub</strong>
             </p>
             <p class="text-gray-600 mb-3 text-sm">
                幸运的是，Qwen1.5-1.8B-Chat 模型也托管在 Hugging Face Hub 上。我们可以使用 <code>huggingface-hub</code> 工具来下载，这个工具通常在 macOS 上兼容性更好。
            </p>
            <ol class="list-decimal list-inside space-y-2 text-sm text-gray-600 mb-4">
                <li>
                    <strong>安装 `huggingface-hub` 库:</strong>
                    <pre><code>pip install huggingface-hub -i https://pypi.tuna.tsinghua.edu.cn/simple</code><button class="copy-button" onclick="copyCode(this.previousElementSibling)"><i class="far fa-copy"></i> 复制</button></pre>
                </li>
                 <li>
                    <strong>使用 `huggingface-cli` 下载模型:</strong> 这个命令会将模型下载到您指定的本地目录 (例如 <code>~/Models/Qwen1.5-1.8B-Chat</code>)。
                    <pre><code># 确保目标目录存在
mkdir -p ~/Models/Qwen1.5-1.8B-Chat

# 下载模型 (注意模型名称是 Qwen/Qwen1.5-1.8B-Chat)
huggingface-cli download Qwen/Qwen1.5-1.8B-Chat --local-dir ~/Models/Qwen1.5-1.8B-Chat --local-dir-use-symlinks False</code><button class="copy-button" onclick="copyCode(this.previousElementSibling)"><i class="far fa-copy"></i> 复制</button></pre>
                    <p class="text-xs mt-1"><code>--local-dir</code> 指定下载路径。<code>--local-dir-use-symlinks False</code> 建议在 macOS 上使用，避免符号链接可能带来的问题。</p>
                </li>
                 <li>
                    <strong>记录模型路径：</strong> 请记住您通过 <code>--local-dir</code> 指定的模型路径 (例如 <code>~/Models/Qwen1.5-1.8B-Chat</code>)，在后续步骤 (如 7.3 验证加载) 中需要使用这个路径。
                 </li>
            </ol>
             <p class="text-gray-600 mb-3 text-sm">
                如果 ModelScope 安装或下载失败，请务必使用 Hugging Face Hub 这个替代方法来获取模型文件。
            </p>
            <h3>7.2 (可选但推荐) 移动模型文件</h3>
            <p class="text-gray-700 mb-2">
                如果您使用 ModelScope 下载并且模型位于默认缓存路径，建议将其移动到更方便管理的位置，例如 <code>~/Models/</code>。如果您使用了 Hugging Face Hub 并已指定了 <code>--local-dir</code>，则无需再次移动。
            </p>
            <pre><code># 仅当使用 ModelScope 且想移动时执行
# 假设默认下载路径是 /Users/your_username/.cache/modelscope/hub/Tongyi-Qianwen/Qwen1.5-1.8B-Chat
# 假设您想移动到的目标路径是 /Users/your_username/Models/
# 注意：请根据您的实际用户名和路径修改！

# 先创建目标目录（如果不存在）
mkdir -p ~/Models/

# 移动模型文件夹
mv ~/.cache/modelscope/hub/Tongyi-Qianwen/Qwen1.5-1.8B-Chat ~/Models/Qwen1.5-1.8B-Chat</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>
             <div class="info-box">
                 <p><i class="fas fa-folder-tree mr-1"></i>请确保您知道模型文件最终存放的**准确路径** (例如 <code>~/Models/Qwen1.5-1.8B-Chat</code>)。<strong>记住这个路径</strong>。</p>
            </div>

            <h3>7.3 验证模型加载 (使用 webchat 在 MPS/CPU 上)</h3>
            <p class="text-gray-700 mb-2">
                运行以下命令启动 `webchat`。将 <code>--model_name_or_path</code> 参数的值**替换为您模型实际存放的路径**。
            </p>
            <pre><code># 假设您的模型在 ~/Models/Qwen1.5-1.8B-Chat
# 确保替换为您的实际路径！
llama-factory-cli webchat \
    --model_name_or_path ~/Models/Qwen1.5-1.8B-Chat \
    --template qwen</code><button class="copy-button" onclick="copyCode(this)"><i class="far fa-copy"></i> 复制</button></pre>
             <details class="my-3">
                <summary><i class="fas fa-cogs mr-1"></i>关于设备选择 (Device Selection)</summary>
                <div class="p-3 bg-gray-50 rounded border mt-2 text-sm text-gray-600">
                    <ul>
                        <li>Llama Factory 可能会尝试自动使用 MPS (如果 PyTorch 检测到可用)。</li>
                        <li>如果遇到问题或想强制使用 CPU，可以查看 <code>llama-factory-cli webchat -h</code> 是否有类似 <code>--device cpu</code> 的参数（具体参数可能随版本变化）。</li>
                        <li>性能提示：即使使用 MPS，速度也可能不理想。CPU 会更慢。请耐心等待模型加载和响应。</li>
                    </ul>
                </div>
            </details>
            <div class="interactive-container">
                <p class="mb-2 font-medium text-gray-800">启动过程模拟 & 访问 Web UI：</p>
                <div class="terminal-output" style="max-height: 200px; overflow-y: auto;">
                    (llama_factory) user@MacBook-Pro LLaMA-Factory % llama-factory-cli webchat --model_name_or_path ~/Models/Qwen1.5-1.8B-Chat --template qwen
                    <br>
                    [INFO] [RANK 0] Initializing LlamaFactory...
                    <br>
                    [INFO] [RANK 0] Initializing model... (Trying MPS or CPU)
                    <br>
                    Loading checkpoint shards: 100%|██████████| 2/2 [00:25<00:00, 12.50s/it] <span class="text-yellow-400">(可能比 GPU 慢很多)</span>
                    <br>
                    [INFO] [RANK 0] Model initialized.
                    <br>
                    [INFO] [RANK 0] Running Gradio server at: http://127.0.0.1:7860 <span class="text-gray-500">(通常监听本地地址)</span>
                    <br>
                    </div>
                 <p class="mt-3 text-sm text-gray-600">
                    <i class="fas fa-desktop mr-1"></i>当看到 <code>Running Gradio server at: http://127.0.0.1:7860</code> 时，表示服务已启动。
                    <br>
                    <i class="fas fa-network-wired mr-1"></i>在浏览器中访问 <code>http://127.0.0.1:7860</code> 或 <code>http://localhost:7860</code>。
                </p>
            </div>
            <p class="text-gray-700 mt-4 mb-2">
                访问 Web UI 后，尝试输入“你好，请问你是谁？”进行对话。请耐心等待响应，因为 MPS/CPU 推理会比较慢。
            </p>
             <div class="success-box mt-4">
                 <p><i class="fas fa-comments mr-1"></i><strong>验证成功 (推理可行)！</strong> 如果模型能够回复您的问题（即使速度较慢），则说明：</p>
                 <ul class="list-disc list-inside ml-4 mt-1 text-sm">
                     <li>模型文件下载完整。</li>
                     <li>Llama Factory 能够加载模型并在 MPS 或 CPU 上运行推理。</li>
                     <li>您的基本环境配置正确。</li>
                 </ul>
                 <p class="mt-2">这表明您可以在 Mac 上使用 Llama Factory 来熟悉界面、配置和进行基础的模型交互。但请牢记微调的性能限制。</p>
                 <p class="mt-2 text-xs">（验证完成后，在终端按 <kbd>Ctrl</kbd>+<kbd>C</kbd> 停止服务。）</p>
            </div>
        </section>

        <section id="cli-overview-macos">
            <h2><i class="fas fa-terminal mr-2"></i>8. Llama Factory CLI 命令概览</h2>
            <p class="text-gray-700 mb-4">
                <code>llama-factory-cli</code> 工具的子命令与 Linux 版本基本相同：
            </p>
            <ul class="list-none space-y-2 text-gray-700">
                <li><i class="fas fa-chevron-right w-4 text-indigo-500"></i> <code>version</code>: 显示版本信息。</li>
                <li><i class="fas fa-chevron-right w-4 text-indigo-500"></i> <code>train</code>: 启动微调（在 Mac 上会非常慢）。</li>
                <li><i class="fas fa-chevron-right w-4 text-indigo-500"></i> <code>eval</code>: 评估模型（同样受性能影响）。</li>
                <li><i class="fas fa-chevron-right w-4 text-indigo-500"></i> <code>infer</code>: 后端推理。</li>
                <li><i class="fas fa-chevron-right w-4 text-indigo-500"></i> <code>webchat</code>: 简单的对话界面（已验证）。</li>
                <li><i class="fas fa-chevron-right w-4 text-indigo-500"></i> <code>webui</code>: <strong>常用命令</strong>，启动功能更全面的 Web UI。推荐使用此命令来熟悉 Llama Factory 的各项功能。</li>
                <li><i class="fas fa-chevron-right w-4 text-indigo-500"></i> <code>export</code>: 导出模型。</li>
            </ul>
             <p class="text-gray-700 mt-4">
                同样，可以使用 <code>llama-factory-cli [command] -h</code> 查看具体命令的帮助。
            </p>
        </section>

        <section id="later-usage">
            <h2><i class="fas fa-play-circle mr-2"></i>9. 后续启动与使用</h2>
            <p class="text-gray-700 mb-4">
                当您完成了首次设置，以后想再次启动 Llama Factory 的 Web 界面时，可以按照以下步骤操作：
            </p>
            <ol class="list-decimal list-inside space-y-3 text-gray-700 mb-4">
                <li>
                    <strong>打开终端 (Terminal)</strong>。
                </li>
                <li>
                    <strong>激活 Conda 环境：</strong>
                    <pre><code>conda activate llama_factory</code><button class="copy-button" onclick="copyCode(this.previousElementSibling)"><i class="far fa-copy"></i> 复制</button></pre>
                </li>
                 <li>
                    <strong>进入 Llama Factory 项目目录：</strong> (请使用您存放项目的实际路径)
                    <pre><code>cd ~/Projects/LLaMA-Factory</code><button class="copy-button" onclick="copyCode(this.previousElementSibling)"><i class="far fa-copy"></i> 复制</button></pre>
                </li>
                 <li>
                    <strong>启动 Web UI 或 WebChat：</strong>
                    <ul class="list-disc list-inside ml-6 mt-2 space-y-2">
                        <li>
                            <strong>启动完整 Web UI (推荐):</strong> 用于训练、评估、对话等。
                            <pre><code># 确保 --model_name_or_path 指向您下载的模型路径
llama-factory-cli webui \
    --model_name_or_path ~/Models/Qwen1.5-1.8B-Chat \
    --template qwen</code><button class="copy-button" onclick="copyCode(this.previousElementSibling)"><i class="far fa-copy"></i> 复制</button></pre>
                             <p class="text-xs text-gray-500 mt-1">Web UI 提供了更丰富的功能，包括模型选择、数据集管理、训练参数配置等，更适合深入学习。</p>
                        </li>
                        <li>
                             <strong>启动简单 WebChat:</strong> 仅用于对话。
                            <pre><code># 确保 --model_name_or_path 指向您下载的模型路径
llama-factory-cli webchat \
    --model_name_or_path ~/Models/Qwen1.5-1.8B-Chat \
    --template qwen</code><button class="copy-button" onclick="copyCode(this.previousElementSibling)"><i class="far fa-copy"></i> 复制</button></pre>
                        </li>
                    </ul>
                     <p class="text-sm text-indigo-700 mt-3"><i class="fas fa-info-circle mr-1"></i><strong>提示：</strong> 确保命令中的 <code>--model_name_or_path</code> 指向您实际存放模型的路径。如果需要，可以查阅 <code>llama-factory-cli webui -h</code> 或 <code>webchat -h</code> 看是否有指定设备 (如 <code>--device mps</code> 或 <code>--device cpu</code>) 的选项。</p>
                </li>
                 <li>
                    <strong>访问 Web 界面：</strong> 终端会显示类似 <code>Running Gradio server at: http://127.0.0.1:7860</code> 的信息。在您的浏览器中打开这个地址 (<code>http://127.0.0.1:7860</code> 或 <code>http://localhost:7860</code>)。
                </li>
                 <li>
                    <strong>停止服务：</strong> 当您使用完毕后，回到运行 Llama Factory 命令的终端窗口，按下 <kbd>Ctrl</kbd> + <kbd>C</kbd> 组合键即可停止服务。
                </li>
                 <li>
                    <strong>退出 Conda 环境 (可选)：</strong> 如果您想退出当前的 Conda 环境，可以运行：
                     <pre><code>conda deactivate</code><button class="copy-button" onclick="copyCode(this.previousElementSibling)"><i class="far fa-copy"></i> 复制</button></pre>
                </li>
            </ol>
        </section>
        <hr class="my-8 border-gray-300">
        <p class="text-center text-gray-600">
            您已完成在 M2 Mac 上部署 Llama Factory 的基本流程和验证。现在，您可以尝试启动 <code>llama-factory-cli webui</code> 来探索完整的界面和功能。请始终牢记在 Mac 上的性能限制，并将重点放在熟悉工具本身。祝学习顺利！
        </p>

    </div>

    <script>
        // 复制按钮功能 (与原指南相同)
        function copyCode(button) {
            // Find the preceding <pre> element
            let pre = button.previousElementSibling;
            while (pre && pre.tagName !== 'PRE') {
                pre = pre.previousElementSibling;
            }
            if (!pre) return; // Should not happen if structure is correct

            const code = pre.querySelector('code');
            if (!code) return; // Should not happen

            const textToCopy = code.innerText;

            navigator.clipboard.writeText(textToCopy).then(() => {
                const originalText = button.innerHTML;
                button.innerHTML = '<i class="fas fa-check"></i> 已复制';
                button.classList.add('bg-green-500');
                button.classList.remove('hover:bg-gray-600');
                setTimeout(() => {
                    button.innerHTML = originalText;
                    button.classList.remove('bg-green-500');
                    button.classList.add('hover:bg-gray-600');
                }, 1500);
            }).catch(err => {
                console.error('复制失败: ', err);
                alert('复制失败，请手动复制。');
            });
        }

        // 模拟激活 Conda 环境 (macOS 版本)
        function simulateActivateEnvMac() {
            const outputDiv = document.getElementById('conda-env-output-macos');
            const basePrompt = '(base) user@MacBook-Pro ~ % ';
            const activatedPrompt = '<span class="text-green-400">(llama_factory)</span> user@MacBook-Pro ~ % ';

            outputDiv.innerHTML = basePrompt + 'conda activate llama_factory';

            setTimeout(() => {
                 outputDiv.innerHTML += '<br>' + activatedPrompt;
            }, 500);
        }
    </script>

</body>
</html>
